WIP: maintenance workflow documentation #262

Ocramius · 2018-10-28T12:20:12Z

This is a stub of the release process that I was slowly putting into words.

As discussed with @carusogabriel and @Majkl578 while at PHP Central Europe, we need to get this automated, and removed from the documentation once that's done (as in: documentation just references the release tool)

TODO:

check how this actually renders
document code review as part of the maintenance workflow
document dependency upgrades as part of the maintenance workflow
document signed tags for releases

…lacholder

…eaking remotes

…gorise change types

…aims of maintainers and contributors

…ease

source/contribute/maintainer.rst

Co-Authored-By: Ocramius <ocramius@gmail.com>

Ocramius · 2018-10-29T12:01:20Z

@jwage can you please talk about this workflow with @doctrine/team-mongodb-odm? I think ORM and ODM are quite different right now, but if we build an automation, we should unify the workflows.

@SenseException I marked it as WIP because it is incomplete, but I don't remember what's missing. Can you check it again, please?

alcaeus · 2018-10-29T12:12:00Z

We'll discuss this at the next ODM hangout.

malarzm · 2018-10-29T12:15:39Z

I think the biggest difference is that ODM's version description is usually linking to CHANGELOG.md which contains description of what changed (and we usually craft it manually). And I personally use github to tag a new release instead of console :)

Ocramius · 2018-10-29T12:22:10Z

I think the biggest difference is that ODM's version description is usually linking to CHANGELOG.md

Good one! What do we do about CHANGELOG.md? I think we should start maintaining it, especially requiring an entry in it for every relevant patch. If we can ensure that, then the release notes (and therefore the git tag message) can be inferred from the latest block in CHANGELOG.md. Should I add it to the document?

And I personally use github to tag a new release instead of console :)

We need signed tags for our releases, especially with the size of our audience. This isn't feasible via Github UI...

malarzm · 2018-10-29T12:42:47Z

So in ODM we always write an entry in CHANGELOG before tagging new release, they usually look like this - list there not always contains all PRs merged, because some are not worthy mentioning (i.e. docs). Sometimes we put more info to the changelog, that usually happens for a minor release (like this one).

Bugfix release notes follow this scheme (copy-paste-fix links):

Maintenance release.

Please see [changelog](https://github.com/doctrine/mongodb-odm/blob/1.2.x/CHANGELOG-1.2.md#125-2018-07-20) for a complete list of fixes.

All issues and pull requests in this release may be found under the [1.2.5 milestone](https://github.com/doctrine/mongodb-odm/issues?q=milestone%3A1.2.5).

We need signed tags for our releases, especially with the size of our audience. This isn't feasible via Github UI...

I can change my ways, no problem 👍

Ocramius · 2018-10-29T12:47:19Z

I can change my ways, no problem +1

I don't want to impede your work, hence my strong focus on automation in this documentation. At some point, I'd like to remove humans from the release process in this organisation.

malarzm · 2018-10-29T13:47:24Z

I can change my ways, no problem +1

I don't want to impede your work, hence my strong focus on automation in this documentation. At some point, I'd like to remove humans from the release process in this organisation.

That was about signing tags and not using github UI ;) FWIW I think maintaing changelog is better as it's easily grep-able.

Majkl578 · 2018-10-29T23:08:01Z

source/contribute/maintainer.rst

+Each of the following steps are documented for humans to perform them
+manually, but maintainers and contributors are highly encouraged to try
+and automate them away into tooling that is commonly available across
+the organisation projects, as well as the community at large.


We also talked about automating PR merges, after passed builds and approvals (and i.e. no blocking label).
Ideally we should also guard automatic merges by Roave/BackwardCompatibilityCheck that would block auto-merge (ideally as a separate CI integration, not part of the Travis build directly).

Yeah, Roave BC is a bit too strict, but we can add our (laxer) rules to CI. Also, I need to make it faster before it is introduced.

Majkl578 · 2018-10-29T23:09:30Z

source/contribute/maintainer.rst

+------------------------------------------------
+
+The primary role of a maintainer, besides being also a contributor,
+is to sort incoming proposals by their category:


As part of this standardization, we SHOULD sync labels across all repositories and also their colors (at least all listed below). Currently it's random.

source/contribute/maintainer.rst

Majkl578 · 2018-10-29T23:13:48Z

source/contribute/maintainer.rst

+   or **MINOR** release (depending on team internal agreement).
+   Consumers should not rely on ``master`` unless they are prepared
+   to adapt their codebase at every potentially breaking change.
+ * ``MAJOR.MINOR.x`` - always to be considered the next planned


Considering that we currently mostly use MAJOR.MINOR, what is the motivation to use MAJOR.MINOR.x?

ORM, DBAL and common started using MAJOR.MINOR with 2.2, while the rest either doesn't have enough branches for it to be called a model or are using MAJOR.MINOR.x.

Fwiw either branch name format works with the website.

source/contribute/maintainer.rst

Majkl578 · 2018-10-29T23:21:20Z

source/contribute/maintainer.rst

+
+Then it is possible to tag a release.
+
+Please note that tags *MUST* be signed. Unsigned releases will be


Suggested change

Please note that tags *MUST* be signed. Unsigned releases will be

Please note that tags **MUST** be GPG-signed by either the maintainer's or Doctrine's GPG key.

Unsigned releases will be

As discussed, as part of automating releases. we may introduce a Doctrine GPG key that will be signed by all maintainers and internally used to create tags.

I don't like the anonymity of a shared GPG key - anyone could sign a malicious tag and hide between the shared identity. I'd advocate against that and suggest we keep signing with individual keys.

Wouldn't be anonymous: it would require trust from the doctrine maintainers

Looking at one tag, would I be able to tell which maintainer signed the tag?

No, it would be done by tooling, not by a person

Even if it's done by tooling, as long as it's triggered by a human (./bin/doctrine release a.b.c) it should be signed by that human. Otherwise, there's no significant advantage to signing with the GitHub key, except that we're maintaining our own key for the sake of it.

Key K is signed as trusted by maintainer A, B, C. Subkey K1 is deployed to a (safe) environment, where the automation takes over tagging and releasing when things are triggered. There won't be a ./bin/doctrine release a.b.c: the aim is to remove it, and completely automate releases as merges happen. Yes, that would be a lot of releases :)

I don't think that's feasible at all at the current time, hence my opposition to this. Let's take things one at a time. If we ever get to the point where we want to do a release on every merge, we can bring this up again. Until that point, let's leave the original suggestion in: people sign tags with their GPG key instead of relying on GitHubs default key.

instead of relying on GitHubs default key.

Yeah, this should never be done anyway 👍

Co-Authored-By: Ocramius <ocramius@gmail.com>

SenseException · 2018-11-04T21:08:57Z

I think this should also work well for changes in the documentation.
@Ocramius Do we need to emphasize that changes in the documentation shouldn't be in the same commits as code changes? Also: New features should get a proper documentation before they can be merged.

Ocramius · 2018-11-04T21:10:54Z

shouldn't be in the same commits as code changes?

I don't mind if the commits overlap or not, but they should probably be in the same patch. I don't think it has to do with the maintenance workflow though: we can put it in issue/PR templates, maybe?

morozov · 2019-01-10T20:46:11Z

source/contribute/maintainer.rst

@@ -31,7 +39,7 @@ locally:

 .. code-block:: console

-    $ git clone git@github.com:username/doctrine2.git doctrine2-orm
+    $ git clone git@github.com:<username>/doctrine2.git doctrine2-orm


This requires an update due to doctrine/orm#7552.

morozov · 2019-01-10T20:49:14Z

source/contribute/maintainer.rst

@@ -59,16 +67,167 @@ Optionally, add any additional contributor/maintainer forks, e.g.:

    $ git remote add romanb git://github.com/romanb/doctrine2.git


This could be reworded to <username> for consistency with the change in git clone ....

carusogabriel · 2019-01-10T23:54:48Z

Gosh, I need to do some research about it, I forget :P

Ocramius · 2019-01-11T12:35:41Z

Folks, I can't get to work on this further in the next weeks: is anybody in @doctrine/team-documentation willing to finish this up?

source/contribute/maintainer.rst

jwage · 2019-02-03T15:50:19Z

@Ocramius I can take the ball.

… maintainer workflow Co-Authored-By: Ocramius <ocramius@gmail.com>

Ocramius · 2019-02-04T13:29:16Z

@jwage thanks!

alcaeus · 2019-04-08T08:42:40Z

source/contribute/maintainer.rst

+Whilst it is possible to automate some of these decisions, humans
+are still better at categorising these changes due to the amount of
+nuances that are involved in the software development process.
+
 Branching Model


This section needs an update after the decision at the EUFOSSA hackathon. See https://github.com/doctrine/automatic-releases#todos for the process.

Ocramius added 14 commits August 29, 2018 14:22

Removed ambiguous username URI bit - replaced with a more obvious p…

38f9102

…lacholder

Documenting that maintainers can fetch all active pull requests by tw…

1922293

…eaking remotes

Documenting primary responsibility of a maintainer to detect and cate…

6d936fd

…gorise change types

Documenting what a critical fix is

a0a93bf

Documenting security fixes

25f9130

Documenting stability purpose

d81baf3

Maintainers should always evaluate whether a BC break is worth it

9e2eee8

Clarifying that Semantic Versioning = SemVer

fef66f7

Documenting the branch names and branching strategy

1e2f812

Documenting that automating the maintainer work should be one of the …

d983267

…aims of maintainers and contributors

Documenting the way in which release versions should behave

a03e176

Example graph of the branching structure of a typical doctrine project

85fb415

Adding 2.0.x (mandatory release branch) attached to the 2.0.0 rel…

272f918

…ease

Documented release process

be1d6d5

Ocramius added Build Related to the build process of the website itself Documentation Documentation related issues WIP Something that is a work in progress. labels Oct 28, 2018

SenseException reviewed Oct 28, 2018

View reviewed changes

source/contribute/maintainer.rst Show resolved Hide resolved

SenseException reviewed Oct 28, 2018

View reviewed changes

source/contribute/maintainer.rst Outdated Show resolved Hide resolved

SenseException reviewed Oct 28, 2018

View reviewed changes

source/contribute/maintainer.rst Outdated Show resolved Hide resolved

SenseException and others added 2 commits October 28, 2018 23:38

Added deprecation policy link

268934a

Co-Authored-By: Ocramius <ocramius@gmail.com>

Added security policy link

21c9761

Co-Authored-By: Ocramius <ocramius@gmail.com>

SenseException requested a review from jwage October 29, 2018 09:39

SenseException approved these changes Oct 29, 2018

View reviewed changes

jwage approved these changes Oct 29, 2018

View reviewed changes

Majkl578 reviewed Oct 29, 2018

View reviewed changes

Majkl578 and others added 3 commits October 30, 2018 10:28

Corrected capitalisation of Doctrine

5607868

Co-Authored-By: Ocramius <ocramius@gmail.com>

Corrected capitalisation of Doctrine

cd92778

Co-Authored-By: Ocramius <ocramius@gmail.com>

Corrected capitalisation of Doctrine

221807b

Co-Authored-By: Ocramius <ocramius@gmail.com>

Ocramius mentioned this pull request Nov 4, 2018

Document how to do releases #152

Closed

Ocramius mentioned this pull request Dec 14, 2018

Document the release process doctrine/dbal#3406

Closed

morozov reviewed Jan 10, 2019

View reviewed changes

sstok reviewed Feb 3, 2019

View reviewed changes

source/contribute/maintainer.rst Outdated Show resolved Hide resolved

Replaced "assuming" with "given" to avoid iterpretation issues in the…

92a6365

… maintainer workflow Co-Authored-By: Ocramius <ocramius@gmail.com>

Ocramius assigned jwage Feb 4, 2019

alcaeus reviewed Apr 8, 2019

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: maintenance workflow documentation #262

WIP: maintenance workflow documentation #262

Ocramius commented Oct 28, 2018 •

edited

Loading

Ocramius commented Oct 29, 2018

alcaeus commented Oct 29, 2018

malarzm commented Oct 29, 2018

Ocramius commented Oct 29, 2018

malarzm commented Oct 29, 2018

Ocramius commented Oct 29, 2018

malarzm commented Oct 29, 2018

Majkl578 Oct 29, 2018

Ocramius Oct 30, 2018 •

edited

Loading

Majkl578 Oct 29, 2018

Majkl578 Oct 29, 2018

alcaeus Oct 30, 2018

jwage Jan 11, 2019

Majkl578 Oct 29, 2018

alcaeus Oct 30, 2018

Ocramius Oct 30, 2018

alcaeus Oct 30, 2018

Ocramius Oct 30, 2018

alcaeus Oct 30, 2018

Ocramius Oct 30, 2018

alcaeus Oct 30, 2018

Ocramius Oct 30, 2018

SenseException commented Nov 4, 2018

Ocramius commented Nov 4, 2018

morozov Jan 10, 2019 •

edited

Loading

morozov Jan 10, 2019

carusogabriel commented Jan 10, 2019

Ocramius commented Jan 11, 2019

jwage commented Feb 3, 2019

Ocramius commented Feb 4, 2019

alcaeus Apr 8, 2019


		Then it is possible to tag a release.

		Please note that tags MUST be signed. Unsigned releases will be

	Please note that tags MUST be signed. Unsigned releases will be
	Please note that tags MUST be GPG-signed by either the maintainer's or Doctrine's GPG key.
	Unsigned releases will be

		@@ -59,16 +67,167 @@ Optionally, add any additional contributor/maintainer forks, e.g.:

		$ git remote add romanb git://github.com/romanb/doctrine2.git

WIP: maintenance workflow documentation #262

Are you sure you want to change the base?

WIP: maintenance workflow documentation #262

Conversation

Ocramius commented Oct 28, 2018 • edited Loading

Ocramius commented Oct 29, 2018

alcaeus commented Oct 29, 2018

malarzm commented Oct 29, 2018

Ocramius commented Oct 29, 2018

malarzm commented Oct 29, 2018

Ocramius commented Oct 29, 2018

malarzm commented Oct 29, 2018

Choose a reason for hiding this comment

Ocramius Oct 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SenseException commented Nov 4, 2018

Ocramius commented Nov 4, 2018

morozov Jan 10, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carusogabriel commented Jan 10, 2019

Ocramius commented Jan 11, 2019

jwage commented Feb 3, 2019

Ocramius commented Feb 4, 2019

Choose a reason for hiding this comment

Ocramius commented Oct 28, 2018 •

edited

Loading

Ocramius Oct 30, 2018 •

edited

Loading

morozov Jan 10, 2019 •

edited

Loading